---
id: listbox
title: Listbox
description: A component for selecting a single or multiple items from a list.
---

<ComponentPreview id="Listbox" />

## Anatomy

To set up the Listbox correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

{/* <Anatomy id="listbox" /> */}

## Examples

### Basic

Here's a basic example of the Listbox component.

<Example id="basic" />

### Controlled

The Listbox component can be controlled by using the `value` and `onValueChange` props. This allows you to manage the
selected value externally.

<Example id="controlled" />

### Disabled Item

Listbox items can be disabled using the `disabled` prop on the collection item.

<Example id="disabled" />

> You can also use the `isItemDisabled` within the `createListCollection` to disable items based on a condition.

### Multiple Selection

You can set the `selectionMode` property as `multiple` to allow the user to select multiple items at a time.

<Example id="multiple" />

### Grouping

The Listbox component supports grouping items. You can use the `groupBy` function to group items based on a specific
property.

<Example id="group" />

## Guides

### Type-Safety

The `Listbox.RootComponent` type enables you to create closed, strongly typed wrapper components that maintain full type
safety for collection items.

This is particularly useful when building reusable listbox components with custom props and consistent styling.

```tsx
import { Listbox as ArkListbox, type CollectionItem } from '@ark-ui/react/listbox'
import { createListCollection } from '@ark-ui/react/collection'

interface ListboxProps<T extends CollectionItem> extends ArkListbox.RootProps<T> {}

const Listbox: ArkListbox.RootComponent = (props) => {
  return <ArkListbox.Root {...props}>{/* ... */}</ArkListbox.Root>
}
```

Then, you can use the `Listbox` component as follows:

```tsx
const App = () => {
  const collection = createListCollection({
    initialItems: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
      { label: 'Svelte', value: 'svelte' },
    ],
  })
  return (
    <Listbox
      collection={collection}
      onValueChange={(e) => {
        // this will be strongly typed Array<{ label: string, value: string }>
        console.log(e.items)
      }}
    >
      {/* ... */}
    </Listbox>
  )
}
```

## API Reference

### Props

<ComponentTypes id="listbox" />

### Context

These are the properties available when using `Listbox.Context`, `useListboxContext` hook or `useListbox` hook.

<ContextType id="listbox" />
